InfoMagic Internet Tools 1993 July/Internet Tools.iso/RockRidge/mail/smail-3.1.28/guide/admin/install

Text File | 1990-10-23 | 21.4 KB | 655 lines

.\" @(#)guide/admin/install    1.2 10/24/90 05:17:51
.NH
Smail Installation Procedure
.PP
The basic procedures for installing the
.B Smail3.1
program and its associated utilities require that you edit a small
number of compile-time configuration files, build dependencies within
all of the smail makefiles, and then build all of the executables and
install them.  Some sites will wish to include the additional step of
writing run-time configuration files, which are described in a later
section.
.NH 2
The Source Release
.PP
When you receive a smail source release and install the sources under
a directory, the following tree should exist:
.RS
.iP README
A plain text file describing the release and general installation
procedures and giving the addresses of useful mailing lists.
.iP compat/
A directory in which a compatibility library is generated containing
functions that do not exist in your system's object libraries.
.iP conf/
A directory containing compile-time configuration files.
.RS
.iP EDITME-dist
A file that should be copied and edited to describe your machine and
the locations in which various files can be found or should be
installed.
.iP arch/
A directory which contains files describing various machine
architectures, such as 32-bit architectures with and without virtual
memory, or 16 bit architectures with extended address spaces.
.iP driver/
A directory which contains files describing various possible driver
configurations.  These files define specifically which director,
router and transport drivers are to be included in the smail binary.
.iP os/
A directory which contains files describing various operating systems
to which smail has been ported.  To as large an extent as is
reasonable, operating system dependencies are described solely within
these files.
.iP lib/
This directory contains shell commands and miscellaneous files used
from smail makefiles to digest configuration information and build
dependencies.
.RE
.iP guide/
A directory containing the source for the various smail guide
documents.
.RS
.iP admin/
This directory contains the troff source for the
.I "Smail Administration and Installation Guide" .
.RE
.iP history
A file describing the history of smail releases, in terms of source
reorganizations and the addition of new capabilities.
.iP man/
A directory containing nroff sources for all man pages included in the
.B smail3.1
release.
.RS
.iP man1/
Man pages for user commands.
.iP man5/
Man pages describing run-time configuration file formats.
.iP man8/
Man pages for administrative commands and other programs that are not
intended to be run directly by users.
.RE
.iP pd/
A directory containing public domain sources that are used by the
smail program or its associated utilities.
.RS
.iP binmail/
A replacement for
.I /bin/mail
that traps mailer requests and sends them to smail.  This is for use
by generic System V sites, and for other sites that are not already
setup to call a mailer program.  This is not normally installed.
.iP getopt/
A public domain release of the System V
.B getopt
library function.  Also included is a getopt command which implements
a super-set of the System V
.I getopt (1)
command.
.iP pathalias/
The
.B pathalias
program by Steve Bellovin, as told to Peter Honeyman with additional
modifications suggested by Landon Noll.  These sources will be used as
a basis for pathalias version 10.
.iP strlib/
An implementation of various string routines.  These will be used for
systems that do not already have these routines in an object library.
.iP uuwho/
A program for viewing map entries distributed through USENET in the
newsgroup
.B comp.mail.maps .
.RE
.iP src/
The source for the smail program.
.RS
.iP directors/
The sources for all director drivers distributed with smail.  Director
drivers handle the low level operations involved with aliasing,
forwarding and the recognition of local user names.
.iP routers/
The sources for all routing drivers.  Routing drivers handle the low
level operations of finding routes to hosts or domains and binding
remote addresses to specific transports.
.iP transports/
The sources for all transport drivers.  Transport drivers perform the
low level operations of mail delivery.
.RE
.iP util/
The sources for various user and administrative utilities distributed
with smail.
.RE
.NH 2
Configuring Smail for Your System
.PP
The first step in configuring smail is to copy the file
.I EDITME-dist ,
in the source directory
.I conf ,
to the file
.I EDITME
in the same directory.  As the name implies, you should then edit this
file to describe your machine.  This file is a shell script that is
used to define variables such as what type of operating system you are
using, the general class of architecture, and where particular data
files and executables should reside.  It is also used to describe,
within a limited range, the default configuration to be used when the
optional runtime configuration files do not exist.
.PP
The
.I EDITME
file itself contains descriptions of all of the variables that can be
defined in this file.  We will not attempt to duplicate all of the
information here, though a few pointers may be useful.
.NH 3
Defining your Operating System
.PP
The variable OS_TYPE defines the basename of a file which should
describe your operating system.  Possible values for OS_TYPE are the
names of files in the directory
.I conf/os .
If none of these files accurately describe your system, then a new
file should be created by copying the file
.I template
to a new name and editing it as appropriate.
.PP
If you port Smail to a new machine, we would appreciate receiving any
patches that were required as well as the os file describing that
machine.  Any reasonable contributions may be included in future
releases.
.NH 3
Defining your Hostnames
.PP
There are a number of variables used to describe names for your
machine.  Usually, most of these variables will be left undefined,
forcing smail to compute the names itself.  Some variables that you
may wish to change describe the domain namespaces in which your
machine resides.  Gateway hosts will often require more hostname
information so that they can handle mail sent to the domains that they
handle, rather than to a specific host within them.
.PP
The most important variable to set is DOMAINS which describes the
domains under which your host resides.
.B Smail3.1
will use a system-dependent algorithm for determining the name for the
local host, such as the
.I gethostname (2)
system call in a BSD operating system, or
.I uname (2)
under System V.  The value of DOMAINS, in combination with the computed
value for your machine's name, is used to form a list of fully
qualified names for your host.  For many sites in the UUCP zone,
DOMAINS should simply be set to ``uucp'', while domain gateways may
need to use multiple values, separated by colons, such as
``uts.amdahl.com:amdahl.com:uucp''.  The first domain name in this
list is special in that it is used in forming the primary (or
.I canonical )
name for your machine.  This name should be unique across all
accessible networks.
.PP
To understand the use of the DOMAINS variable, let's use the value
that is used for the gateway machine to the domain
.B amdahl.com .
The machine name for this gateway is
.B amdahl .
Its value for DOMAINS is ``uts.amdahl.com:amdahl.com:uucp''.  With
this configuration, the primary name for the gateway is
.B amdahl.uts.amdahl.com
with other names being
.B amdahl.amdahl.com
and
.B amdahl.uucp.
.PP
Additional names can be given to your machine, unrelated to the name
smail computes for your host.  This can be useful for gateways that
wish to be recognized under the names of domains for which they are a
gateway.  The variable GATEWAY_NAMES should be set to this
colon-separated list of alternate hostnames.  As an example, the
gateway host ``amdahl'' sets GATEWAY_NAMES to
``uts.amdahl.com:amdahl.com''.  Thus, an address such as
.B [e-mail]
or
.B [e-mail]
will reach a responsible person rather than being rejected.
.PP
As a final note on defining host names, the variable VISIBLE_NAME can
be used to define the host name used in addresses referring to the
local host.  This name will be used by in contexts where the
canonical name is not required by DDN standards and can be used to
group a collection of machines under a domain.  When resolving
addresses, the VISIBLE_NAME string is not matched as a local hostname
unless it also appears in either HOSTNAMES or GATEWAY_NAMES.
.PP
For example, most suns within the
.B uts.amdahl.com
domain set VISIBLE_NAME to ``uts.amdahl.com''.  Mail originating from
.B chongo
on a Sun named
.B eek
would appear to have been sent from
.B [e-mail] ,
rather than from
.B [e-mail] .
The domain gateway knows where the user
.B chongo
wishes to receive his mail.  Thus, replies to mail sent from
.B eek
will be returned directly to
.B chongo 's
mailbox rather than passing back through
.B eek .
.NH 3
Directories for Data Files and Executables
.PP
As distributed, programs intended to be run by users will be installed
under the directory
.I /usr/local ,
while programs intended to be run only from cron jobs or from other
smail programs will be installed under
.I /usr/lib/smail .
Configuration files will also be searched for under
.I /usr/lib/smail .
In addition, spool and log files will be placed in a hierarchy under
.I /usr/spool/smail .
These locations can be changed by setting the variables SMAIL_BIN_DIR,
LIB_DIR and SPOOL_DIRS .
.PP
As the name implies, SPOOL_DIRS can contain more than one directory
name.  This can be used to define multiple spool directory
hierarchies.  When a new message comes in, an attempt is made to write
it into the first hierarchy in this list.  If the file cannot be
written, the next hierarchy is tried, then the next and so on until
the spool file is written or no more directory names exist in the
list.  For example, with a value of
``/usr/spool/smail:/usr2/spool/smail,'' if the filesystem containing
.I /usr/spool/smail
fills up or runs out of
.I I -nodes,
an attempt is made to write a spool file under
.I /usr2/spool/smail
instead.  Only if this second filesystem is also filled up will smail
give up in trying to spool the message.
.PP
Some other path    names that you may wish to change are:
.iP SMAIL_NAME
the pathname used by smail utilities in executing the mailer.
Normally, this will be
.I /usr/lib/sendmail
which is where Berkeley commands and utilities expect the mailer to
reside, and where many public domain programs also expect the mailer
to reside.
.iP OTHER_SMAIL_NAMES
miscellaneous full pathnames under which smail will be installed.
.I /bin/rmail
should be in this list, to trap mail coming in over uucp.
.I /bin/rsmtp
can also be in this list.  When invoked under this name, batched SMTP
commands will be read from standard input, allowing SMTP to be used
over UUCP between cooperating hosts running smail.
.iP NEWALIASES
an alternate pathname for the
.B mkaliases
utility, which processes an alias file for use by an
.I aliasfile
director.  By installing it as
.B newaliases ,
some compatibility can be maintained with the
.B sendmail
utility of the same name.  The primary difference is that the new
version is not set-uid and cannot be safely made so.  Thus, users
which do not have write access to the directory containing the aliases
file cannot use this command.
.iP ALIASES_FILE
the pathname of the primary aliasing file.  This is the file that is
processed by the
.B mkaliases
utility.  It is also the only alias file defined in the default smail
configuration.  To maintain compatibility with
.B sendmail
under 4.2BSD and 4.3BSD, this should be set to ``/usr/lib/aliases''.
However, you may wish to have this file under LIB_DIR with
the other smail configuration files.  This can be done by setting it
simply to ``aliases''.
.NH 2
Building the Smail Program and Utilities
.PP
After EDITME and other compile-time configuration files have been
adjusted (see the section
.B "Configuring Smail for Your System" )
you are ready to start the build.  The first step in building the
smail program and utilities on your machine is to generate all of the
.I Makefile
dependencies.  This step will allow you to modify compile-time
configuration files and header files without worrying about which
compilations will depend on them.  This information will be stored in
the Makefiles that need them.  To generate these dependencies, use the
command:
.DS I
make depend
.DE
at the top of the smail source hierarchy.  This will take a while, so
you may wish to send the standard output and standard error to a file and
put the command in background.  This can be done in the Bourne or Korn
Shell with the command:
.DS I
make depend > mkdep.out 2>&1 &
.DE
In the C-shell, use the command:
.DS I
make depend >& mkdep.out &
.DE
You can watch the progress of the operation with the command:
.DS I
tail -f mkdep.out
.DE
When the dependencies have been built, build all of the executables with
the command:
.DS I
make
.DE
On an Amdahl 5890 this takes two minutes or more depending upon
machine load.  For other machines, this may take between a half hour
and two hours.
.NH 2
Verifying the Smail Program
.PP
It is a good idea to verify that the smail program works before
actually installation it and the utilities around it.  A simple way to
do this is to run some commands.  To start out, try the command:
.DS I
src/smail -bv -v \fIyour-name\fP@\fIlocal-host\fP
.DE
Here
.I your-name
should be your login name on the local host, and
.I local-host
should be a name for the local host.
.LP
This should produce the following output:
.DS I
director user matched user \fIyour-user\fP
\fIyour-user\fP ... deliverable
.DE
.PP
Next, become superuser (\fBroot\fP on most UN*X machines) and try the
command:
.DS I
src/smail -v \fIyour-name\fP
.DE
This should produce output such as:
.DS I
make directory /usr/spool/smail
make directory /usr/spool/smail/input
new spool file is /usr/spool/smail/input/0dMgpi-000089
.DE
Next give a message on standard input such as:
.DS I
Subject: This is a first test of Smail3.1

*hi mom, please send money*
\&.
.DE
The dot, on a line by itself, will terminate the message.  Sending an
end of file character will also suffice.  This should produce:
.DS I
make directory /usr/spool/smail/log
write_log:new msg: from \fIyour-user\fP
director user matched user \fIyour-user\fP
transport local uses driver appendfile
write_log:\fIyour-user\fP ... delivered
make directory /usr/spool/smail/msglog
.DE
Note that smail creates any directories that it requires, if they do
not already exist.  You should now have mail.
.PP
If all of this worked, then there is probably nothing seriously wrong
with the smail program itself.
.NH 2
Installing the Programs
.PP
When you are satisfied that the setup appears to be okay, try
installing the programs on your machine by becoming superuser and
executing the command:
.DS I
make install
.DE
This will create any required directories and will copy the binaries
and a small number of data files into their final locations.  The
installation process will create the following:
.iP "Under the LIB_DIR directory"
.B getopt ,
.B pathalias ,
.B makedb ,
.B arpatxt ,
.B mkline ,
.B mksort ,
.B dcasehost ,
.B mkdbm ,
.B mkpath ,
.B mkhpath ,
.B mkuuwho ,
.B pathmerge ,
.B checkerr ,
.B savelog ,
.B getmap ,
.B gleem ,
and
.B unsharmap .
Also copied into the LIB_DIR directory are the files
.I mkpath.awk ,
.I mkuuwho.awk
and
.I mkpath.sed
which are used by some of the above programs, and the file
.I COPYING
which states your rights and responsibilities in further distribution
of the smail programs.
.iP "Under the SMAIL_BIN_DIR directory"
.B uuwho
and
.B mkaliases .
Also, the smail binary is linked to the names
.B smail ,
.B mailq ,
.B pathto ,
.B optto ,
.B uupath ,
.B runq
and
.B rsmtp .
.PP
The smail binary will also be copied to whatever was named in the
.I EDITME
file as the SMAIL_NAME.  Normally, this will be
.I /usr/lib/sendmail .
It will also be copied to any pathnames listed in OTHER_SMAIL_NAMES,
such as
.I /bin/rmail
or
.I /bin/rsmtp .
Also, if you defined a value for NEWALIASES in the
.I EDITME
file, such as
.I /usr/local/bin/newaliases ,
then the
.B mkaliases
program will be copied to that name.
.PP
All of the copies of the smail binary will be owned by root and have
the set-uid bit set.
.B Smail3.1
has been designed so that it does not need to run as root, though this
creates the potential for a a variety of trojan horse attacks which
must be carefully handled through configuration files.  It is
generally easier to install smail as a setuid to root program so that
the potential for trojan horse attacks is more easily managed.
.PP
The current implementation of
.B mkaliases
is a Bourne shell script which cannot be made secure as a setuid
program.  Thus, only users that can write to the directory containing
the aliases file can successfully run this program.  This behavior is
incompatible with the
.B newaliases
program distributed with Berkeley's
.B sendmail
program.  This is expected to change in a future release.
.NH 2
Smail Queue Runs
.PP
When messages block for some reason and smail decides that it would be
best to retry deliver at a later time, messages will be left in the
.I input
spool directory.  In order to reattempt delivery, a smail process must
scan through this directory at intervals looking for work.  This can
either be accomplished by starting up one smail process that scans for
work, sleeps for a set time period, and then scans again, or
.I cron (8)
can be used to start up a process to scan for work.
.PP
To startup a single smail process that scans for work at intervals,
execute the following command from your machine's
.I /etc/rc
file:
.DS I
/usr/lib/sendmail \-q20m
.DE
This will scan for work every twenty minutes.  To scan for work once per
hour use an argument of
.B \-q1h
instead.  This command will automatically put itself in background, so
you do not need to use an ampersand after the command.
.PP
To execute smail periodically from cron, use a line such as:
.DS I
0,20,40 * * * * /usr/lib/sendmail -q
.DE
Each invocation of smail with this command will perform exactly one
scan through the
.I input
spool directory, which will be done in foreground.
.PP
Systems using the
.B "System V"
cron program can safely put this in the crontab file for
.B root ,
or in any other crontab file.
Sites running the 4.3BSD version of cron can put a line in
.I /usr/lib/crontab
such as:
.DS I
0,20,40 * * * * root /usr/lib/sendmail -q
.DE
.NH 2
Listening for SMTP Requests
.PP
If your site supports Berkeley networking, then you can use smail to
process interactive SMTP requests.  This can be done either from a
non-exiting smail daemon, or from the 4.3BSD or Sun
.I inet
daemon.  The decision as to whether to use a smail daemon, or the inet
daemon depends upon how much mail passes through your site and whether
or not you can always spare 300K of virtual memory.
.PP
To invoke a smail daemon at system boot time, execute the following
command from
.I /etc/rc :
.DS I
/usr/lib/sendmail \-bd
.DE
This can be combined with the
.B \-q
flag described in the previous section, so executing the command:
.DS I
/usr/lib/sendmail \-bd \-q20m
.DE
will handle listening for SMTP connection requests and the processing
of the
.I input
directory at intervals.
.PP
To invoke smail from the 4.3BSD
.I inetd
program, put the following line in
.I /etc/inetd.conf :
.DS I
smtp    stream    tcp    nowait    root    /usr/local/smtpd smtpd
.DE
If
.I smtpd
was installed in a different directory, use whatever is appropriate in
place of
.I /usr/local/smtpd .
To invoke smail from the SunOS
.I inetd
program, put the following line in
.I /etc/servers :
.DS I
smtp    tcp    /usr/local/smtpd
.DE
.PP
If you have some other form of networking connection that can be used
to create a bi-directional interactive connection, you can use the
.I smtpd
program, or the command
.I "/usr/lib/sendmail -bs"
to receive SMTP requests over that bi-directional connection.
.NH 2
Cleaning Up After Smail
.PP
Smail creates log files.  If log files are not truncated in a
reasonable manner, then they will eventually fill up all available
space.  To handle log file truncation, a shell script,
.I savelog
is provided to cycle a log through a set of files, where no more than
a set number of files are kept.  As an example, the command:
.DS I
/usr/lib/smail/savelog /usr/spool/smail/log/logfile
.DE
will rename the smail log file to
.I /usr/spool/smail/log/OLD/logfile.1 .
If this file already exists, it will be renamed to
.I logfile.2
before the original logfile is renamed, and so on up to
.I logfile.7 .
Whenever
.I logfile.6
is renamed to
.I logfile.7 ,
this last file is simply removed.
.PP
If the
.I compress
program is available, then
.I logfile.2
through
.I logfile.7
are kept in a compressed form with an extension of
.I .Z .
Different compression programs may also be used, generating logfiles
with different extensions.
.PP
Running the above savelog command from cron once per day will thus
keep the last seven days worth of logfile data, much of it in a
compressed form.
.PP
Occasionally, smail will run into a problem that requires the
attention of a mail administrator.  An example of this is an error in
the configuration files.  Rather than continually retrying a message
and continually failing, messages are moved into an
.I error
directory under the spool directory hierarchy.  The utility
.B checkerr
can be called from cron to check up on this directory at intervals,
and send a report on newly failed messages to the address
.B Postmaster .
This script should be run periodically, perhaps once per day, under a
user that can write to the
.I error
spool directory.  Normally, this requires that it run as root, though
the
.I chown (1)
command can be used to assign this directory to an alternate user.